'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 1997 Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH LISTEN 8 "Apr 3, 1997"
.SH NAME
listen \- network listener daemon
.SH SYNOPSIS
.LP
.nf
\fB/usr/lib/saf/listen\fR [\fB-m\fR \fIdevstem\fR] \fInet_spec\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBlisten\fR process ``listens'' to a network for service requests, accepts
requests when they arrive, and invokes servers in response to those service
requests. The network listener process may be used with any connection-oriented
network (more precisely, with any connection-oriented transport provider) that
conforms to the Transport Layer Interface (TLI) Specification.
.sp
.LP
The listener internally generates a pathname for the minor device for each
connection; it is this pathname that is used in the \fButmpx\fR entry for a
service, if one is created. By default, this pathname is the concatenation of
the prefix \fB/dev/\fR\fInetspec\fR with the decimal representation of the
minor device number. In either case, the representation of the minor device
number will be at least two digits (for example, 05 or 27), or longer when it
is necessary to accommodate minor device numbers larger than 99.
.SH SERVER INVOCATION
.sp
.LP
When a connection indication is received, the listener creates a new transport
endpoint and accepts the connection on that endpoint. Before giving the file
descriptor for this new connection to the server, any designated STREAMS
modules are pushed and the configuration script is executed, (if one exists).
This file descriptor is appropriate for use with either TLI (see
\fBt_sync\fR(3NSL) ) or the sockets interface library.
.sp
.LP
By default, a new instance of the server is invoked for each connection. When
the server is invoked, file descriptor 0 refers to the transport endpoint, and
is open for reading and writing. File descriptors 1 and 2 are copies of file
descriptor 0; no other file descriptors are open. The service is invoked with
the user and group IDs of the user name under which the service was registered
with the listener, and with the current directory set to the HOME directory of
that user.
.sp
.LP
Alternatively, a service may be registered so that the listener will pass
connections to a standing server process through a FIFO or a named stream,
instead of invoking the server anew for each connection. In this case, the
connection is passed in the form of a file descriptor that refers to the new
transport endpoint. Before the file descriptor is sent to the server, the
listener interprets any configuration script registered for that service using
\fBdoconfig\fR(3NSL), although \fBdoconfig\fR is invoked with both the
\fBNORUN\fR and \fBNOASSIGN\fR flags. The server receives the file descriptor
for the connection in a \fBstrrecvfd\fR structure using an \fBI_RECVFD\fR
\fBioctl\fR(2).
.sp
.LP
For more details about the listener and its administration, see
\fBnlsadmin\fR(8).
.SH OPTIONS
.sp
.ne 2
.na
\fB\fB-m\fR\fIdevstem\fR\fR
.ad
.RS 13n
The listener will use \fIdevstem\fR as the prefix for the pathname.
.RE

.SH FILES
.sp
.LP
\fB/etc/saf/\fR\fIpmtag\fR\fB/\fR\fI*\fR
.SH SEE ALSO
.sp
.LP
.BR ioctl (2),
.BR doconfig (3NSL),
.BR nlsgetcall (3NSL),
.BR nlsprovider (3NSL),
.BR t_sync (3NSL),
.BR streamio (4I),
.BR attributes (7),
.BR nlsadmin (8),
.BR pmadm (8),
.BR sac (8),
.BR sacadm (8)
.sp
.LP
\fI\fR
.SH NOTES
.sp
.LP
When passing a connection to a standing server, the user and group IDs
contained in the \fBstrrecvfd\fR structure will be those for the listener (that
is, they will both be 0); the user name under which the service was registered
with the listener is not reflected in these IDs.
.sp
.LP
When operating multiple instances of the listener on a single transport
provider, there is a potential race condition in the binding of addresses
during initialization of the listeners, if any of their services have
dynamically assigned addresses. This condition would appear as an inability of
the listener to bind a static-address service to its otherwise valid address,
and would result from a dynamic-address service having been bound to that
address by a different instance of the listener.
